---
description: Hasura Cloud API reference
keywords:
  - hasura
  - cloud
  - docs
  - API
  - API reference
sidebar_position: 14
sidebar_label: Hasura Cloud API reference
sidebar_class_name: cloud-icon
---

import TOCInline from '@theme/TOCInline';
import ProductBadge from '@site/src/components/ProductBadge';
import Thumbnail from '@site/src/components/Thumbnail';

# Hasura Cloud API Reference

<ProductBadge free pro ee />

## Introduction

Hasura Cloud provides a GraphQL API to interact with services to create and manage your Cloud Projects using any GraphQL
client.

## Endpoint

The Hasura Cloud API endpoint is `https://data.pro.hasura.io/v1/graphql`.

## Authentication

Authentication is done using a Personal Access Token that you can create from the Hasura Cloud Dashboard. You can find
this option in the "My Account" section on bottom left.

<Thumbnail
  src="/img/api-reference/create-new-hasura-access-token_cloud_2.8.1.png"
  alt="Create a Hasura Cloud personal access token"
/>

Once you have created the token it should be used as a header in your requests in the format:
`Authorization: pat <token>`.

:::info Note

This token can be used to authenticate against all of your Hasura Cloud APIs and Projects. It is only revealed once on
creation. Make sure you keep it secure. The token will be valid until you delete it from the dashboard.

:::

## APIs

Each Hasura Cloud Project is backed by an API entity called "Tenant", with a distinct "Tenant ID" which is different
from the "Project ID". Each Project is associated with a Tenant. In some cases, like with the Metrics API, the Project
ID is used instead of Tenant ID.

<TOCInline toc={toc} filterTOC={'apis'} />

### Create a Project

```graphql
mutation createProject {
  createTenant(
    cloud: "aws"
    region: "us-east-2"
    envs: [{ key: "HASURA_GRAPHQL_CORS_DOMAIN", value: "*" }, { key: "MY_ENV_VAR_1", value: "my value 1" }]
  ) {
    id
    name
  }
}
```

### Get Project Tenant id

```graphql
query getProjectTenantId {
  projects_by_pk(id: "7a79cf94-0e53-4520-a560-1b02bf522f08") {
    id
    tenant {
      id
    }
  }
}
```

### Get Tenant details

```graphql
query getTenantDetails {
  tenant_by_pk(id: "7a79cf94-0e53-4520-a560-1b02bf522f08") {
    id
    slug
    project {
      id
      endpoint
    }
  }
}
```

### Delete a Tenant

```graphql
mutation deleteTenant {
  deleteTenant(tenantId: "7a79cf94-0e53-4520-a560-1b02bf522f08") {
    status
  }
}
```

### Get ENV Vars

```graphql
query getTenantENV {
  getTenantEnv(tenantId: "7a79cf94-0e53-4520-a560-1b02bf522f08") {
    hash
    envVars
  }
}
```

### Update ENV Vars

```graphql
mutation updateTenantEnv {
  updateTenantEnv(
    tenantId: "7a79cf94-0e53-4520-a560-1b02bf522f08"
    currentHash: "6902a395d70072fbf8d36288f0eacc36c9d82e68"
    envs: [
      { key: "HASURA_GRAPHQL_ENABLE_CONSOLE", value: "true" }
      { key: "ACTIONS_ENDPOINT", value: "https://my-actions-endpoint.com/actions" }
    ]
  ) {
    hash
    envVars
  }
}
```

### Create GitHub Preview App {#api-ref-create-preview-app}

Schedules the creation of a Hasura Cloud Project with Migrations and Metadata from a branch of a GitHub repo.

```graphql
mutation createGitHubPreviewApp {
  createGitHubPreviewApp(
    payload: {
      githubPersonalAccessToken: "<github_access_token>"
      githubRepoDetails: { branch: "main", owner: "my-org", repo: "my-repo", directory: "backend/hasura" }
      projectOptions: {
        cloud: "aws"
        region: "us-east-2"
        plan: "cloud_free"
        name: "my-app_name"
        envVars: [
          { key: "HASURA_GRAPHQL_AUTH_HOOK", value: "https://my-webhook.com" }
          { key: "MY_ENV_VAR_1", value: "my value 1" }
        ]
      }
    }
  ) {
    githubPreviewAppJobID
  }
}
```

#### Input arguments

| Argument                               | Description                                                                                                                                                                                                                                                                                                                                             |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `githubPersonalAccessToken`            | GitHub personal access token for Hasura Cloud to access the Migrations and Metadata from your repository. Refer to GitHub docs on how to create a [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). The token should have read access to the repository. |
| under `githubRepoDetails`: `owner`     | GitHub repository owner (user or organization)                                                                                                                                                                                                                                                                                                          |
| under `githubRepoDetails`: `repo`      | GitHub repository name.                                                                                                                                                                                                                                                                                                                                 |
| under `githubRepoDetails`: `branch`    | Name of the branch from which to create a Preview App.                                                                                                                                                                                                                                                                                                  |
| under `githubRepoDetails`: `directory` | Path to the Hasura Project directory (typically created by the Hasura CLI) containing Migrations and Metadata. The path should be relative to the project's root directory.                                                                                                                                                                             |
| under `projectOptions`: `name`         | Name of the Preview App. A Hasura Cloud project will be created with the same name. Can contain lowercase characters, numbers and hyphens.                                                                                                                                                                                                              |
| under `projectOptions`: `cloud`        | The cloud provider to deploy the Preview App on. A Hasura Cloud project will be created in the specified cloud provider. Available: `aws` and `gcp`.                                                                                                                                                                                                    |
| under `projectOptions`: `region`       | The region within the cloud provider to deploy the Preview App on. A Hasura Cloud project will be created in the specified region. Refer to the Hasura Cloud dashboard for available options.                                                                                                                                                           |
| under `projectOptions`: `plan`         | Pricing tier of the created Preview App. Available options: `cloud_free` and `cloud_payg` (corresponds to Free Tier and Professional Tier respectively).                                                                                                                                                                                                    |
| under `projectOptions`: `envVars`      | ENV vars to be set for the created Preview App.                                                                                                                                                                                                                                                                                                         |

#### Output Fields

| Argument                | Description                                                                                                                                                                                                                                                                                                                             |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `githubPreviewAppJobID` | Job ID of the Preview App creation job. This does not mean the Preview App is created, the ID identifies the job responsible for creating the Preview App. For the status of the Preview App creation, query the [`getPreviewAppCreationStatus` API](/api-reference/cloud-api-reference.mdx#api-ref-fetch-preview-app-creation-status). |

### Fetch Preview App Creation Status {#api-ref-fetch-preview-app-creation-status}

Preview App creation is a multistep process. This query fetches the status of the Preview App creation. The input
`jobID` is the same ID obtained in the output of the
[Create GitHub Preview App](/api-reference/cloud-api-reference.mdx#api-ref-create-preview-app) mutation.

```graphql
query getPreviewAppCreationStatus($jobId: uuid!) {
  jobs_by_pk(id: $jobId) {
    id
    status
    tasks {
      id
      name
      task_events {
        id
        event_type
        public_event_data
        error
      }
    }
  }
}
```

#### Input Arguments

| Argument | Description                                                                                                                                                                                                                                                |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`     | Job ID of the Preview App creation job. The ID identifies the job responsible for creating the Preview App. This can be obtained from the output of the [`createGitHubPreviewApp` API](/api-reference/cloud-api-reference.mdx#api-ref-create-preview-app). |
